<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Java Service Wrapper - JMX Control</title>
<style media="all" type="text/css">
            @import url("./style/wrapper.css");
        </style>
</head>
<body bgcolor="#eeeeff" marginheight="0" marginwidth="0" leftmargin="0" topmargin="0" alink="#023264" vlink="#023264" link="#525D76" text="#000000">
<map name="wrapperLogo">
<area href="http://wrapper.tanukisoftware.org" coords="90,90,88" shape="circle">
</map>
<map name="wrapperTitle">
<area href="http://www.tanukisoftware.com" coords="28,32,176,48" shape="rect">
</map>
<table cellpadding="0" cellspacing="0" width="100%" border="0">
<tr>
<td valign="top" width="180">
<table cellpadding="0" cellspacing="0" width="100%" border="0">
<tr>
<td width="180"><img usemap="#wrapperLogo" border="0" height="180" width="180" src="images/WrapperLogo.png"></td>
</tr>
<tr>
<td>
<table cellpadding="4" cellspacing="0" width="100%" border="0">
<tr>
<td nowrap="true">
<div id="menu">
<script language="JavaScript">//@@MENU_TOP@@</script>
<div>
<b>Essentials</b>
<div>
<a href="introduction.html">Introduction</a>
</div>
<div>
<a href="integrate.html">Integration Methods</a>
</div>
<div>
<a href="properties.html">Configuration Properties</a>
</div>
<div>
<a href="launch.html">Launching Your Application</a>
</div>
<div>
<b>
                        &gt;&gt;
                        <a href="donate.html">Show Your Support</a>
                        &lt;&lt;
                    </b>
</div>
<div>
<a href="sponsors.html">Sponsors</a>
</div>
</div>
<div>
<b>Documentation</b>
<div>
<a href="jmx.html">JMX Control</a>
</div>
<div>
<a href="security-model.html">Security Model</a>
</div>
<div>
<a href="example.html">Feature Examples</a>
</div>
<div>
<a href="debugging.html">Debugging Your Application</a>
</div>
<div>
<a href="troubleshooting.html">Troubleshooting</a>
</div>
<div>
<a href="faq.html">FAQ</a>
</div>
<div>
<a href="release-notes.html">Release Notes</a>
</div>
<div>
<a href="history.html">Project History</a>
</div>
<div>
<a href="javadocs.html">Javadocs API</a>
</div>
<div>
<a href="buttons.html">Buttons</a>
</div>
<div>
<a href="authors.html">Authors</a>
</div>
<div>
<a href="license.html">License</a>
</div>
</div>
<div>
<b>Download</b>
<div>
<a href="http://sourceforge.net/project/showfiles.php?group_id=39428&package_id=31591">Binaries</a>
</div>
<div>
<a href="http://sourceforge.net/project/showfiles.php?group_id=39428&package_id=33658">Source Code</a>
</div>
</div>
<div>
<b>Get Involved</b>
<div>
<a href="http://sourceforge.net/projects/wrapper/">Source Forge</a>
</div>
<div>
<a href="http://svn.sourceforge.net/viewvc/wrapper/">Subversion Repository</a>
</div>
<div>
<a href="http://sourceforge.net/tracker/?group_id=39428">Issue Tracking</a>
</div>
<div>
<a href="http://sourceforge.net/mail/?group_id=39428">Mailing Lists and Archives</a>
</div>
<div>
<a href="http://sourceforge.net/forum/?group_id=39428">Forums (Old)</a>
</div>
</div>
</div>
<script language="JavaScript">//@@MENU_BOTTOM@@</script>
<p>
<b>Hosted by:</b>
<br>
<a href="http://sourceforge.net/projects/wrapper/"><img alt="SourceForge" border="0" height="31" width="88" src="http://sourceforge.net/sflogo.php?group_id=39428"></a>
<br>
</p>
</td>
</tr>
</table>
</td>
</tr>
</table>
</td><td valign="top" width="*">
<table cellpadding="0" cellspacing="0" width="100%" border="0">
<tr>
<td colspan="3"><img height="4" src="images/spacer.gif"></td>
</tr>
<tr>
<td align="center" height="90" colspan="2"><a href="http://wrapper.tanukisoftware.org"><img border="0" height="90" width="728" src="images/OfflineAd728x90.png"></a></td><td rowspan="5"><img width="4" src="images/spacer.gif"></td>
</tr>
<tr>
<td height="49" width="435"><img usemap="#wrapperTitle" border="0" height="49" width="435" src="images/WrapperTitle.png"></td><td valign="bottom" align="right" width="*"><a href="donate.html"><img border="0" height="16" width="300" src="images/DonationRequest.png"></a></td>
</tr>
<tr>
<td height="4" colspan="2"><img height="4" width="500" src="images/BorderTop.png"></td>
</tr>
<tr>
<td colspan="2">
<table cellspacing="0" cellpadding="0" width="100%" border="0">
<tr>
<td valign="top" width="4"><img height="496" width="4" src="images/BorderLeft.png"></td><td bgcolor="#ffffff" valign="top" width="*" colspan="2">
<table cellpadding="4" cellspacing="0" width="100%" border="0">
<tr>
<td nowrap="true" align="center"><font zcolor="#115b77" color="#8888aa" size="5"><b>JMX Control</b></font></td>
</tr>
<tr>
<td>
<title>JMX Control</title>
     
    
<a name="N10009"></a>
<table cellpadding="2" cellspacing="0" width="100%" border="0">
<tr>
<td bgcolor="#8888aa" class="sectionheader1" width="*"><font color="#eeeeee" size="4"><b>Controlling the Java Service Wrapper using JMX</b></font></td>
</tr>
<tr>
<td><img height="4" width="1" src="./images/spacer.gif"></td>
</tr>
<tr>
<td>
        
        
<p>
            The Java Service Wrapper provides a pair of JMX MBean interfaces
            which make it possible to control the Wrapper using a JMX interface.
            This section will describe how to configure your JMX enabled
            application so that the MBeans provided with the Java Service
            Wrapper are available.
        </p>
        
<ul>
            
<li>
                
<a href="#jconsole">JConsole</a>
            
</li>
            
<li>
                
<a href="#jboss">JBoss</a>
            
</li>
            
<li>
                
<a href="#mx4j">MX4J</a>
            
</li>
            
<li>
                
<a href="#sun">Sun JMX Reference Implementation</a>
            
</li>
        
</ul>
        
<a name="jconsole"></a>
<table cellpadding="2" cellspacing="0" width="100%" border="0">
<tr>
<td rowspan="3" width="10"><img height="1" width="10" src="./images/spacer.gif"></td><td bgcolor="#9999bb" class="sectionheader2" width="*"><font color="#eeeeee" size="3"><b>JConsole</b></font></td>
</tr>
<tr>
<td><img height="4" width="1" src="./images/spacer.gif"></td>
</tr>
<tr>
<td>
            
            
<p>
                Sun's JDK 5.0 includes the
                <a href="http://java.sun.com/developer/technicalArticles/J2SE/jconsole.html">Java Monitoring and Management Console (JConsole) tool</a>.
                See the above link for details, but JConsole makes it easy to connect
                to properly configured JVMs and monitor and manage their various
                functions.
            </p>
            
<p>
                For security reasons, the ability to remotely monitor a JVM is not
                enabled by default.  To enable this functionality it is necessary
                to define the <tt>com.sun.management.jmxremote</tt>
                system property when launching the JVM.   This can be done using the wrapper
                by specifying a JVM parameter as follows.  See the
                <a href="prop-java-additional-n.html">wrapper.java.additional.&lt;n&gt;</a>
                property for details of its usage:
            </p>
            
<table cellspacing="0" cellpadding="0" width="100%" border="0" class="listing">
<tr>
<td bgcolor="#eeeeee" class="listingcell"><font color="#444444">
<pre class="listingpre">wrapper.java.additional.1=-Dcom.sun.management.jmxremote</pre>
</font></td>
</tr>
</table>
            
<p>
                The Wrapper currently provides 2 MBean interfaces.   The primary MBean,
                <tt>org.tanukisoftware.wrapper.jmx.WrapperManagerMBean</tt>,
                provides basic information about the Wrapper and JVM as well as the
                ability to stop and restart the JVM as well as trigger a full thread dump.
                The registration of this MBean is controlled by setting the
                <tt>org.tanukisoftware.wrapper.WrapperManager.mbean</tt>
                system property.  It is enabled by default.
            </p>
            
<p>
                The second MBean, <tt>org.tanukisoftware.wrapper.jmx.WrapperManagerTestingMBean</tt>,
                makes it possible to trigger various failure states for testing and should
                not be made enabled outside of a testing environment.
                The registration of this MBean is controlled by setting the
                <tt>org.tanukisoftware.wrapper.WrapperManager.mbean.testing</tt>
                system property.  It is disabled by default.
            </p>
            
<table cellspacing="0" cellpadding="0" width="100%" border="0" class="listing">
<tr>
<td bgcolor="#eeeeee" class="listingcell"><font color="#444444">
<pre class="listingpre">wrapper.java.additional.1=-Dcom.sun.management.jmxremote
wrapper.java.additional.2=-Dorg.tanukisoftware.wrapper.WrapperManager.mbean=true
wrapper.java.additional.3=-Dorg.tanukisoftware.wrapper.WrapperManager.mbean.testing=false</pre>
</font></td>
</tr>
</table>
            
<p>
                The registered Wrapper MBeans will show up on the MBean tab of the JConsole
                interface under the <tt>org.tanukisoftware.wrapper</tt>
                package.
            </p>
        
</td>
</tr>
</table>
        
<a name="jboss"></a>
<table cellpadding="2" cellspacing="0" width="100%" border="0">
<tr>
<td rowspan="3" width="10"><img height="1" width="10" src="./images/spacer.gif"></td><td bgcolor="#9999bb" class="sectionheader2" width="*"><font color="#eeeeee" size="3"><b>JBoss</b></font></td>
</tr>
<tr>
<td><img height="4" width="1" src="./images/spacer.gif"></td>
</tr>
<tr>
<td>
            
            
<p>
                Registering the Java Service Wrapper's MBean interfaces with JBoss is
                surprising simple.  This assumes that you have already gotten JBoss
                integrated with the Java Service Wrapper.  See the
                <a href="integrate.html">Integration</a> section, in particular
                the example using JBoss.  This explanation assumes that you have
                installed all of the Wrapper files in the locations described in the
                JBoss integration example.  Particularly the
                <tt>wrapper.jar</tt> file is assumed to be
                located in the <tt>${jboss.home}/lib</tt>
                directory.
            </p>
            
<p>
                JBoss allows you to register as an MBean, any Object which implements
                an interface whose name is the same as the class, appended by "MBean".
                The Wrapper provides two such classes in the
                <tt>org.tanukisoftware.wrapper.jmx</tt> package.
                <tt>WrapperManager</tt> and
                <tt>WrapperManagerTesting</tt>.  The first
                provides several functions to restart and stop the JVM as well as
                providing other information about the Java Service Wrapper.  The
                second class exposes a few methods which can be useful in the testing
                cycle.  They are broken out in case you wish to not include them in
                a final product release.  See the <a href="javadocs.html">javadocs</a>
                for more details.
            </p>
            
<p>
                To register both of the above MBeans, create an XML file named
                <tt>java-service-wrapper-service.xml</tt> in
                the <tt>${jboss.home}/server/default/deploy</tt>
                directory.  The file should contain the following:
            </p>
            
<table cellspacing="0" cellpadding="0" width="100%" border="0" class="listing">
<tr>
<td bgcolor="#eeeeee" class="listingcell"><font color="#444444">
<pre class="listingpre">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;!DOCTYPE server&gt;
&lt;server&gt;
    &lt;classpath archives="wrapper.jar" codebase="../../lib"/&gt;
    
    &lt;mbean code="org.tanukisoftware.wrapper.jmx.WrapperManager"
           name="JavaServiceWrapper:service=WrapperManager"/&gt;
    
    &lt;mbean code="org.tanukisoftware.wrapper.jmx.WrapperManagerTesting"
           name="JavaServiceWrapper:service=WrapperManagerTesting"/&gt;
&lt;/server&gt;</pre>
</font></td>
</tr>
</table>
            
<p>
                Notice that the location of the <tt>wrapper.jar</tt>
                jar file is relative to the location of the XML file.
            </p>
            
<p>
                Upon saving the file, JBoss should detect it and register your new
                MBeans almost immediately.  No need to restart JBoss.  Pretty Cool.
            </p>
            
<p>
                Now, to actually use the new MBeans, simply point your browser to
                JBoss's JMX interface at:
                <a href="http://localhost:8080/jmx-console/">http://localhost:8080/jmx-console/</a>
                You should notice a <tt>JavaServiceWrapper</tt>
                Agent with two MBeans, <tt>WrapperManager</tt>
                and <tt>WrapperManagerTesting</tt>.
                Selecting either beans will present you with a set of attributes
                and actions provided by the MBean.
            </p>
        
</td>
</tr>
</table>
        
<a name="mx4j"></a>
<table cellpadding="2" cellspacing="0" width="100%" border="0">
<tr>
<td rowspan="3" width="10"><img height="1" width="10" src="./images/spacer.gif"></td><td bgcolor="#9999bb" class="sectionheader2" width="*"><font color="#eeeeee" size="3"><b>MX4J</b></font></td>
</tr>
<tr>
<td><img height="4" width="1" src="./images/spacer.gif"></td>
</tr>
<tr>
<td>
            
            
<p>
                To do.  (This section is incomplete and just a jumble of my notes at this point.
                Feel free to send in any suggestions for this section)
            </p>
            
<p>
                
<a href="http://mx4j.sourceforge.net/">MX4J</a>
            
</p>
        
</td>
</tr>
</table>
        
<a name="sun"></a>
<table cellpadding="2" cellspacing="0" width="100%" border="0">
<tr>
<td rowspan="3" width="10"><img height="1" width="10" src="./images/spacer.gif"></td><td bgcolor="#9999bb" class="sectionheader2" width="*"><font color="#eeeeee" size="3"><b>Sun JMX Reference Implementation</b></font></td>
</tr>
<tr>
<td><img height="4" width="1" src="./images/spacer.gif"></td>
</tr>
<tr>
<td>
            
            
<p>
                To do.  (This section is incomplete and just a jumble of my notes at this point.
                Feel free to send in any suggestions for this section)
            </p>
            
<p>
                Sun's reference implementation is just that, a reference implementation.
                There are not a fixed set of steps that you can follow to register the
                the Wrapper's MBeans.  Each application tends to have created their own
                custom way of registering such beans.
            </p>
            
<p>
                Although many applications have defined their own syntax, Sun has defined
                MLET tags, short for Management Applet, as a means for defining MBeans.
                Their syntax is described in the javadocs for the 
                <a href="http://java.sun.com/j2ee/1.4/docs/api/javax/management/loading/MLet.html">javax.management.loading.MLet</a>
                class.  The following MLET tags can be used to register the MBeans provided
                with the Wrapper.  Notice that they are not really XML.
            </p>
            
<table cellspacing="0" cellpadding="0" width="100%" border="0" class="listing">
<tr>
<td bgcolor="#eeeeee" class="listingcell"><font color="#444444">
<pre class="listingpre">&lt;MLET
    CODE = org.tanukisoftware.wrapper.jmx.WrapperManager
    ARCHIVE = "../lib/wrapper.jar"
    NAME = JavaServiceWrapper:service=WrapperManager&gt;
&lt;MLET
    CODE = org.tanukisoftware.wrapper.jmx.WrapperManagerTesting
    ARCHIVE = "../lib/wrapper.jar"
    NAME = JavaServiceWrapper:service=WrapperManagerTesting&gt;</pre>
</font></td>
</tr>
</table>
            
<p>
                More information is available on Sun's
                <a href="http://java.sun.com/products/JavaManagement/index.html">Java Managagement Extensions (JMX) Home Page</a>.
            </p>
        
</td>
</tr>
</table>
    
</td>
</tr>
</table>

</td>
</tr>
<tr>
<td align="right" id="author">
<p>
<i>by Leif Mortenson</i>
</p>
</td>
</tr>
</table>
<script language="JavaScript">//@@BODY_SECTION@@</script></td><td valign="bottom" width="4"><img height="496" width="4" src="images/BorderRight.png"></td>
</tr>
</table>
</td>
</tr>
<tr>
<td align="right" height="4" colspan="2"><img height="4" width="500" src="images/BorderBottom.png"></td>
</tr>
</table>
</td>
</tr>
</table>
<table cellpadding="2" cellspacing="0" border="0" width="100%">
<tr>
<td id="copyright" align="left"><font color="#525D76" size="-1" face="arial,helvetica,sanserif"><i>
                            Copyright &copy;1999-2004 by <a href="http://www.tanukisoftware.com">Tanuki Software</a>.
                            All Rights Reserved.
                        </i></font></td><td align="right"><font color="#525D76" size="-1" face="arial,helvetica,sanserif"><i>
                            last modified:
                            <script language="JavaScript"> document.write(document.lastModified); </script></i></font></td>
</tr>
</table>
</body>
</html>
